GitLab Pages/Vuepress生成项目文档和博客

最近在给公司架构一个新的项目，要求同时写出一个完整的文档，由于正好在浏览 vue 的 GitHub 浏览相关项目时，看到了 Vuepress，所以尝试了一把，所以把开发中的积累写下来。 :::

GitLab Pages 原理 ​

首先了解一下 GitLab Pages 运行的原理。与 GitHub 不同的是，GitLab 需要上传一个 .gitlab-ci.yml 的文件，同时生成的项目文件必须要到 /public 目录中，见详情。

## .gitlab-ci.yml

image: node:9.11.1

pages:
  cache:
    paths:
      - node_modules/

  script:
    - npm install
    - npm run docs:build
  artifacts:
    paths:
      - public
  only:
    - master

Vuepress ​

你可以将 vuepress 安装到全局，也可以将其安装到项目中，我建议选择第二种，后面介绍一下原因

# 创建并进入工程

mkdir project-name
cd project-name

创建package.json

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  },
  "devDependencies": {
    "vuepress": "^0.14.2"
  }
}

# 安装依赖
yarn install # 或 npm install

# 创建并进入docs目录
mkdir docs
cd docs

# 创建一个 markdown 文件
echo '# Hello VuePress' > README.md

# 启动项目
yarn docs:dev # 或 npm run docs:dev

# 编译项目至 '/project-name/public' 中
yarn docs:dev # 或 npm run docs:dev

遇到的坑 ​

其实到这里只是简单的启动了一个 vuepress 项目，但是你还应该花点时间去仔细阅读一下官网的主题配置，去配置你自己的各种导航，并注意下的页面的设置（主要是主页）。

• valine 的引用必须放到 mounted 中，否则无法编译，报错，window is undefined

修改主题 ​

另外 vuepress 适合撸项目文档，至于你要用它来写博客，它并没有分类、标签这样的配置，需要你去修改主题，有两种方式：

1. 将主题文件放到 project-name/docs/.vuepress/theme 中，然后创建一个 Layout.vue 文件：

.
└─ .vuepress
   └─ theme
      └─ Layout.vue

这儿和开发一个正常的 Vue 应用程序是一样的。完全取决于你如何组织你的主题。

2. 从依赖中引用主题，要使用 npm 依赖项的主题，请在 .vuepress/config.js 中提供一个 theme 选项：

module.exports = {
  theme: 'reco',
}

郑重推荐 vuepress-theme-reco ，查看 展示 既没有脱离默认主题的简洁，又增加了分类、分页、标签等功能。

# 安装
yarn add vuepress-theme-reco # npm install vuepress-theme-reco

持续更新中。。。 ​